Shareware Super Platinum 8

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Super Platinum 8 / Shareware Super Platinum 8.iso / mac / BACKUP / FORAG100.ZIP;1 / FORAGE.DOC < prev next >

Wrap

Text File | 1994-01-01 | 13.3 KB | 344 lines

=============================================================================== ================= ================= ================= USER MANUAL FOR THE FORAGE COMMAND ================= ================= ================= =============================================================================== The FORAGE ("For Age") program is Copyright (C) 1992 by Pinnacle Software, CP 386 Mount Royal, Quebec Canada H3P 3C6 U.S. Office: Box 714 Airport Road, Swanton, Vermont 05488 USA Customer Support Service (514) 345-9578 Free 9600 bps files BBS (514) 345-8654 -==*==- Created for Pinnacle Software by Timothy Campbell, 1250 Laird #1A, Montreal, Quebec, Canada H3P 2T2 =============================================================================== OVERVIEW =============================================================================== FORAGE lets you find the name of the newest (or oldest) file in a directory, and pass that name to a DOS command. This may not be something you have to do every day, but when you need to do it, you'll discover that DOS doesn't have an easy method to do that kind of thing. Usually you end up doing a DIR (sorted by date, perhaps) and reading through it until you find the file you want. But so many jobs are date- and time-dependant that we need a utility like FORAGE to let us automate these tasks. TO INSTALL FORAGE: Copy all of the files in the FORAGE package to a directory that is located in your DOS PATH. For details about the PATH command, consult your DOS manual. =============================================================================== HOW FORAGE WORKS =============================================================================== NOTE: This tutorial assumes you understand the use of wildcards in file masks. For example, the DOS command DIR *.DAT uses the "*" wildcard character to show a directory of all files with a DAT extension. For more details about wildcards, consult your DOS manual. FORAGE is a DOS command which accepts command-line parameters. The simplest application is as follows: FORAGE N *.* When you type this command at the DOS prompt, FORAGE tells you the name of the newest file in the current directory. (Later on, we'll see how you can pass that filename to another DOS command.) The "N" stands for "Newest". You can replace it with "O", as follows: FORAGE O *.* This would tell you the name of the oldest file in the current directory. If you also needed to know the size of the oldest file, you could have FORAGE call the DIR command, as follows: FORAGE O *.* DIR One frequent requirement in business is to move old data to diskette. You can copy the oldest file to a diskette as follows: FORAGE O *.* COPY @@ A: The @@ means "the file you found". If @@ is not specified, it is assumed that it goes at the end of the command. Thus, the following two commands are equiv- alent: FORAGE N *.* DIR FORAGE N *.* DIR @@ Getting back to the example of saving old data to diskette, you'll find that operations of that nature are very easy to do when you use FORAGE in a batch (.BAT) file. For a detailed example, showing how to move old data to diskette, consult the section entitled "SAMPLE BATCH FILES". Some additional examples are given later on. See "MORE EXAMPLES". =============================================================================== COMMAND DEFINITION =============================================================================== The FORAGE command uses any of these formats: FORAGE age mask FORAGE age mask command FORAGE age mask command pre-fname FORAGE age mask command @@ post-fname FORAGE age mask command pre-fname @@ post-fname In standard notation, the formal definition is as follows: FORAGE age mask [ command [pre-fname] @@ [post-fname] ] The parameters are: age Age specification, either [N]ewest or [O]ldest You can use a full word, but only the first letter is checked mask File mask, using wildcards, to set the range of files to check For example, *.DAT checks all files with an extension of DAT For details about wildcards, consult your DOS manual command DOS command (fully qualified, or in current PATH) If none given, reports the name of file on console pre-fname Command-line parameters to pass BEFORE the filename @@ Indicates where the filename goes when calling the command If @@ is not specified, the filename is assumed to go last post-fname Command-line parameters to pass AFTER the filename =============================================================================== MORE EXAMPLES =============================================================================== EXAMPLE: FORAGE FUNCTION: Displays two help screens, explaining how to use FORAGE EXAMPLE: FORAGE O *.* FUNCTION: Displays the name of the oldest file in the directory EXAMPLE: FORAGE N *.* FUNCTION: Displays the name of the newest file in the directory EXAMPLE: FORAGE N C:\DOS\*.* FUNCTION: Displays the name of the newest file in the directory C:\DOS\ EXAMPLE: FORAGE N C:\DOS\*.EXE FUNCTION: Displays the name of the newest EXE file in the directory C:\DOS\ EXAMPLE: FORAGE O *.DAT DEL FUNCTION: Deletes the oldest file in the directory with a DAT extension EXAMPLE: FORAGE O \DATA\*.DAT DEL FUNCTION: Deletes oldest DAT file in \DATA\ directory of the current drive EXAMPLE: FORAGE N C:\TEXT\*.TXT MYBATCH.BAT FUNCTION: Passes the name of the newest TXT file in C:\TEXT\ to the batch file MYBATCH.BAT (where it is accessible as the symbol %1) EXAMPLE: FORAGE O *.DAT C:\MYPGMS\COPYOLD.EXE /v @@ /d/r FUNCTION: Passes the name of the oldest DAT file to the COPYOLD program, along with some command-line parameters before and after the filename. If the oldest file was named MYDATA.DAT, it would be as if you typed this command: COPYOLD /v MYDATA.DAT /d/r EXAMPLE: FORAGE newest *.* testnew @@ -x -y FUNCTION: Passes the name of the newest file to the testnew program, followed by the command-line parameters. If the oldest file was named MYFILE.TXT, it would be as if you typed this command: testnew MYFILE.TXT -x -y =============================================================================== RETURN CODES =============================================================================== When you use FORAGE in a batch file, you should use "IF ERRORLEVEL" to check if the utility actually found a file. +-----------------------------------------------------------------------------+ | **IMPORTANT** When using "IF ERRORLEVEL", you MUST check the higher values | | first! In other words, check 255 before 1, and 1 before 0. This is | | because of the way "IF ERRORLEVEL" works. See your DOS manual for details. | +-----------------------------------------------------------------------------+ FORAGE sets ERRORLEVEL as follows: ERRORLEVEL REASON ---------- ------ 0 No problems -- file was found 1 No file was found to match the mask 255 Program error, or help screen =============================================================================== SAMPLE BATCH FILES =============================================================================== NOTE: This is not a tutorial for batch file programming. To find out more about this useful, powerful feature of DOS, consult your DOS manual. If you plan to do any batch programming, you should obtain a copy of our "SEE Utilities". These can be obtained from our support BBS, or can be ordered as part of our "Amazing Shareware Promotion". View or print the text file AMAZE.DOC (included with FORAGE) for details. The FORAGE package includes several sample batch files. These can be viewed or edited with a standard text editor program (e.g. DOS EDIT, or a word-processor in generic "DOS Text" mode). These batch files are provided for study rather than for immediate use. But with a few minor modifications, you may find that they're just what you need! The batch files are: SAVEOLD.BAT Copies the oldest file in the directory with a DAT extension to a diskette, then deletes the file. SAFE.BAT A backup program that uses the PKZIP file compression utility (created by Phil Katz of PKWare) to perform a quick and easy backup of your current directory. This is ideal for people who wish to make safety copies of their work several times per day. SAFE maintains up to three backups (in compressed form) on a diskette. By using two or more diskettes in this way, you can have plenty of backups! It's easy to use SAFE: whenever you take a coffee break, just type SAFE and walk away. Now there's no reason to be without a backup! NOTE: The PKZIP utility is NOT included in the FORAGE package, but it can be found on almost any BBS in the world. You can also call our support BBS and download a fine freeware alternative to PKZIP, named LHA. The batch file can then be modified to use that compression utility instead. If you have PKZIP, you can use SAFE immediately. Make sure that these files are in your DOS PATH: --------- Included with FORAGE --------- ---Other--- FORAGE.EXE SAFE.BAT, PINNACLE.EXE PKZIP.EXE GETKEY.EXE SAFE2.BAT PKUNZIP.EXE ---------------------------------------- ----------- Then log to a directory on your hard disk. Insert a blank diskette in the A: drive, then type SAFE at the DOS prompt. This will backup all files. You can also back up a subset by entering a file mask. For example: SAFE *.DAT SAFE2.BAT This batch file is called by SAFE.BAT =============================================================================== LEGAL NOTICE =============================================================================== FORAGE is presented on an "as is" basis, with no warranties or guarantees expressed or implied. The user bears complete responsibility for assessing the usefulness and applicability of FORAGE to his or her application. Under no circumstances will the author accept liability for any damages arising from the use or misuse of FORAGE or its accompanying files. =============================================================================== FREE USAGE AND SOURCE CODE =============================================================================== FORAGE is distributed as FREEWARE, which means that, while we retain full copy- right, we encourage you to use it -- at no cost -- and pass around UNALTERED copies of the package. See the file VENDOR.DOC (included in the FORAGE package) for complete distribution details. The Turbo Pascal source code for FORAGE may be purchased for in-house use only, for $25. The nonexclusive remarketing license for FORAGE, which entitles you to market or distribute the FORAGE program and documentation (except source code) under a different name as your own product, either as-is or modified, is $138 (source code is included in this price). Remit payment by cheque or money order made out to Pinnacle Software. Make out cheque in U.S. or Canadian funds, drawn on a U.S. or Canadian bank. =============================================================================== THANK-YOU! =============================================================================== Thank-you for trying FORAGE! If you find FORAGE useful, and you own a modem, you can express your apprecia- tion by uploading a complete copy of FORAGE to your favourite BBS. Once you've done that, consider FORAGE "paid for", and use it in good health! If you DON'T own a modem, please give a good friend a copy to enjoy. Please keep FORAGE together with its original files. If your package is incomplete, you can get a fresh copy from our free files BBS, along with some other great software. You can reach our BBS at 514-345-8654, 24 hours per day, at up to 9600 bps (V32). You can download as much as you want, starting with your first call. If you run out of time, call right back! There is no charge for this service; it's our way of distributing our various freeware and shareware products. For additional details, see the text file AMAZE.DOC.